home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tcl / handles.z / handles
Text File  |  1998-10-30  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))                                                    HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tcl_HandleAlloc, Tcl_HandleFree, Tcl_HandleTblInit, Tcl_HandleTblRelease,
  10.      Tcl_HandleTblUseCount Tcl_HandleWalk, Tcl_HandleXlate - Dynamic, handle
  11.      addressable tables.
  12.  
  13.  
  14. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.      #include <tclExtend.h>
  16.  
  17.      void_pt
  18.      Tcl_HandleTblInit (const char *handleBase,
  19.                         int         entrySize,
  20.                         int         initEntries);
  21.  
  22.      int
  23.      Tcl_HandleTblUseCount (void_pt  headerPtr,
  24.                             int      amount);
  25.  
  26.      void
  27.      Tcl_HandleTblRelease (void_pt headerPtr);
  28.  
  29.      void_pt
  30.      Tcl_HandleAlloc (void_pt   headerPtr,
  31.                       char     *handlePtr);
  32.  
  33.      void_pt
  34.      Tcl_HandleXlate (Tcl_Interp *interp,
  35.                       void_pt     headerPtr,
  36.                       const char *handle);
  37.  
  38.      void_pt
  39.      Tcl_HandleWalk (void_pt   headerPtr,
  40.                      int      *walkKeyPtr);
  41.  
  42.      void
  43.      Tcl_WalkKeyToHandle (void_pt   headerPtr,
  44.                           int       walkKey,
  45.                           char     *handlePtr);
  46.  
  47.      void
  48.      Tcl_HandleFree (void_pt headerPtr,
  49.                      void_pt entryPtr);
  50.  
  51. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  52.      The Tcl handle facility provides a way to manage table entries that may
  53.      be referenced by a textual handle from Tcl code.  This is provided for
  54.      applications that need to create data structures in one command, return a
  55.      reference (i.e. pointer) to that particular data structure and then
  56.      access that data structure in other commands. An example application is
  57.      file handles.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))                                                    HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74.      A handle consists of a base name, which is some unique, meaningful name,
  75.      such as `ffffiiiilllleeee' and a numeric value appended to the base name (e.g.
  76.      `file3').  The handle facility is designed to provide a standard
  77.      mechanism for building Tcl commands that allocate and access table
  78.      entries based on an entry index.  The tables are expanded when needed,
  79.      consequently pointers to entries should not be kept, as they will become
  80.      invalid when the table is expanded.  If the table entries are large or
  81.      pointers must be kept to the entries, then the the entries should be
  82.      allocated separately and pointers kept in the handle table.  A use count
  83.      is kept on the table.  This use count is intended to determine when a
  84.      table shared by multiple commands is to be release.
  85.  
  86.    TTTTccccllll____HHHHaaaannnnddddlllleeeeTTTTbbbbllllIIIInnnniiiitttt
  87.      Create and initialize a Tcl dynamic handle table.  The use count on the
  88.      table is set to one.
  89.  
  90.      Parameters:
  91.        oooo _h_a_n_d_l_e_B_a_s_e - The base name of the handle, the handle will be returned
  92.        in the form "baseNN", where NN is the table entry number.
  93.        oooo _e_n_t_r_y_S_i_z_e - The size of an entry, in bytes.
  94.        oooo _i_n_i_t_E_n_t_r_i_e_s - Initial size of the table, in entries.
  95.  
  96.      Returns:
  97.        A pointer to the table header.
  98.  
  99.    TTTTccccllll____HHHHaaaannnnddddlllleeeeTTTTbbbbllllUUUUsssseeeeCCCCoooouuuunnnntttt
  100.      Alter the handle table use count by the specified amount, which can be
  101.      positive or negative.  Amount may be zero to retrieve the use count.
  102.  
  103.      Parameters:
  104.        oooo _h_e_a_d_e_r_P_t_r - Pointer to the table header.
  105.        oooo _a_m_o_u_n_t - The amount to alter the use count by.
  106.  
  107.      Returns:
  108.        The resulting use count.
  109.  
  110.    TTTTccccllll____HHHHaaaannnnddddlllleeeeTTTTbbbbllllRRRReeeelllleeeeaaaasssseeee
  111.      Decrement the use count on a Tcl dynamic handle table.  If the count goes
  112.      to zero or negative, then release the table.
  113.  
  114.      Parameters:
  115.        oooo _h_e_a_d_e_r_P_t_r - Pointer to the table header.
  116.  
  117.    TTTTccccllll____HHHHaaaannnnddddlllleeeeAAAAlllllllloooocccc
  118.      Allocate an entry and associate a handle with it.
  119.  
  120.      Parameters:
  121.        oooo _h_e_a_d_e_r_P_t_r - A pointer to the table header.
  122.        oooo _h_a_n_d_l_e_P_t_r - Buffer to return handle in. It must be big enough to hold
  123.        the name.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))                                                    HHHHaaaannnnddddlllleeeessss((((3333TTTTccccllll))))
  137.  
  138.  
  139.  
  140.      Returns:
  141.        A pointer to the allocated entry (user part).
  142.  
  143.    TTTTccccllll____HHHHaaaannnnddddlllleeeeXXXXllllaaaatttteeee
  144.      Translate a handle to a entry pointer.
  145.  
  146.      Parameters:
  147.        oooo _i_n_t_e_r_p - A error message may be returned in result.
  148.        oooo _h_e_a_d_e_r_P_t_r - A pointer to the table header.
  149.  
  150.        o _h_a_n_d_l_e - The handle assigned to the entry.
  151.  
  152.      Returns:
  153.        A pointer to the entry, or NULL if an error occured.
  154.  
  155.    TTTTccccllll____HHHHaaaannnnddddlllleeeeWWWWaaaallllkkkk
  156.      Walk through and find every allocated entry in a table.  Entries may be
  157.      deallocated during a walk, but should not be allocated.
  158.  
  159.      Parameters:
  160.        oooo _h_e_a_d_e_r_P_t_r - A pointer to the table header.
  161.        oooo _w_a_l_k_K_e_y_P_t_r - Pointer to a variable to use to keep track of the place
  162.        in the table.  The variable should be initialized to -1 before the
  163.        first call.
  164.      Returns:
  165.        A pointer to the next allocated entry, or NULL if there are not more.
  166.  
  167.    TTTTccccllll____WWWWaaaallllkkkkKKKKeeeeyyyyTTTTooooHHHHaaaannnnddddlllleeee
  168.      Convert a walk key, as returned from a call to Tcl_HandleWalk into a
  169.      handle.  The Tcl_HandleWalk must have succeeded.
  170.  
  171.      Parameters:
  172.        oooo _h_e_a_d_e_r_P_t_r - A pointer to the table header.
  173.        oooo _w_a_l_k_K_e_y - The walk key.
  174.        oooo _h_a_n_d_l_e_P_t_r - Buffer to return handle in. It must be big enough to hold
  175.        the name.
  176.  
  177.    TTTTccccllll____HHHHaaaannnnddddlllleeeeFFFFrrrreeeeeeee
  178.      Frees a handle table entry.
  179.  
  180.      Parameters:
  181.        oooo _h_e_a_d_e_r_P_t_r - A pointer to the table header.
  182.        oooo _e_n_t_r_y_P_t_r - Entry to free.
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.